home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / lisp / psgml / README.psgml.z / README.psgml
Encoding:
Text File  |  1998-05-21  |  10.2 KB  |  318 lines
  1. This is the READ ME file for psgml.el version 1.0       -*- text -*-
  2.  
  3.    PSGML is a major mode for editing SGML documents.  It works with
  4. GNU Emacs 19.19 and later or with XEmacs 19.13.
  5.  
  6. This distribution should contain the following source files:
  7.     psgml.el
  8.     psgml.texi
  9.     psgml-other.el
  10.     psgml-lucid.el
  11.     psgml-edit.el
  12.     psgml-parse.el
  13.     psgml-dtd.el
  14.     psgml-info.el
  15.         psgml-charent.el
  16.     psgml-api.texi    -- internals documentation
  17.     psgml-api.el    -- Extra functions for the API
  18.     iso88591.map
  19.     Makefile.in
  20.  
  21. In addition the distribution contains the formatted versions of the
  22. documentation files (psgml.info, ...). But the compiled elisp code is
  23. no longer supplied. You will have to byte compile the files before
  24. PSGML will achieve usable speed.
  25.  
  26. PSGML now comes with autoconf support. See INSTALL for generic
  27. instructions. Run
  28.  
  29.     sh configure
  30.     make
  31.  
  32. and possibly
  33.  
  34.     make install
  35.  
  36. If you are using xemacs, you can run give the argument `--with-xemacs'
  37. to configure, or use `make xemacs'.
  38.  
  39. Instead of using configure you can load the psgml-main.el file and run
  40. the command psgml-compile-files. Then you have to set load-path or
  41. move the .elc files.
  42.  
  43. Send bug reports, comments and suggestions to lenst@lysator.liu.se.
  44.  
  45. New in version 1.0
  46.  
  47. * Main changes
  48.  
  49. ** Support for general entities
  50.  
  51. ** Support for short reference
  52.  
  53. ** Support for catalog files
  54.  
  55. ** New mechanism for caching parsed DTD
  56.  
  57. ** Includes commands to list various aspects of the DTD
  58.  
  59. * Entity support
  60.  
  61. PSGML will recognize entity references (except in attribute values). If
  62. the entity is a general text entity, PSGML will also parse the content
  63. of the entity. To support this PSGML has a new entity manager with a
  64. new mechanism for looking up entities (see belove).
  65.  
  66. Short references are also supported, for the short reference delimiters
  67. from the concrete reference syntax.
  68.  
  69. There are some new and changed commands to complete the entity support:
  70.  
  71. ** Command: `sgml-expand-entity-reference'
  72.  
  73. Insert the text of the entity referenced at point.
  74.  
  75. ** Command: `sgml-expand-all-shortrefs'
  76.  
  77. Expand all short references in the buffer. Short references to text
  78. entities are expanded to the replacement text of the entity, other
  79. short references are expanded into general entity references. If
  80. argument, `to-entity', is non-nil, or if called interactive with
  81. numeric prefix argument, all short references are replaced by generally
  82. entity references.
  83.  
  84. ** Command: `sgml-normalize'
  85.  
  86. Changed to expand short references also. Normalize buffer by filling in
  87. omitted tags and expanding empty tags. Argument `to-entity' controls
  88. how short references are expanded as with `sgml-expand-all-shortrefs'.
  89.  
  90. * Fontification
  91.  
  92. If `sgml-set-face' is true and the DTD has been activated, PSGML will
  93. automatically set the face of markup in the buffer.
  94.  
  95. First the current line is parsed and fontified. If this would mean
  96. parsing more than 500 chars, wait 1 second first.
  97.  
  98. The rest of the buffer is fontified after 6 seconds idle time.
  99.  
  100. Fontification can be interrupted by any input event.
  101.  
  102. The buffer can be fontified initially if `sgml-auto-activate-dtd' is
  103. true.
  104.  
  105. * New entity manager
  106.  
  107. The new entity manager will handle an entity reference thus:
  108.  
  109. ** If the entity has a system identifier, the entity manager will first
  110. try and call the functions on `sgml-sysid-resolve-functions' with the
  111. system identifier as argument, and if any function returns non-nil
  112. assume that the function has handled the entity.
  113.  
  114. ** If the entity has a system identifier and
  115. `sgml-system-identifiers-are-preferred' is non-nil, the system
  116. identifier will be used as a file name relative to the file containing
  117. the entity declaration.
  118.  
  119. ** Next the entity manager will try the catalog, and
  120.  
  121. ** if not found there use the `sgml-public-map'.
  122.  
  123. ** Finally if the entity has not been found and it has a system
  124. identifier, this will be used as a file name.
  125.  
  126. Note: `sgml-system-path' is no longer used for entity lookup.
  127.  
  128. The catalog files searched is given by the variable
  129. `sgml-local-catalogs' and `sgml-catalog-files'. The
  130. `sgml-catalog-files' variable is initialized from the environment
  131. variable `SGML_CATALOG_FILES' (should be a colon separated list of
  132. files). The `sgml-local-catalogs' variable is assumed to be set in a
  133. files local variables.
  134.  
  135. File names for external entities (e.g system identifiers) are relative
  136. to the directory containing the file declaring the entity.
  137.  
  138. The `sgml-public-map' is initialized from the environment variable
  139. `SGML_PATH'.
  140.  
  141. `sgml-system-path' defaults to nil.
  142.  
  143. Supports most of sgmls substitutions for sgml-public-map. Supported:
  144. %%, %N, %P, %S, %Y, %C, %L, %O, %T, %V. Unsupported: %D, %X, %A, %E,
  145. %I, %R, %U. Note: that %D is and alias for %C in PSGML (historical
  146. accident).
  147.  
  148. * New and changed options
  149.  
  150. ** `sgml-recompile-out-of-date-cdtd'
  151.  
  152. ** New options for insert-element:
  153. `sgml-insert-missing-element-comment' and
  154. `sgml-insert-end-tag-on-new-line'.
  155.  
  156. ** `sgml-validate-files' and slight change of `sgml-validate-command'
  157.  
  158. The variable `sgml-validate-command' can now be a list of strings. The
  159. strings can contain %-sequences that will be expanded: %b to buffer
  160. file name, %s to SGML Declaration file, either the value of
  161. sgml-declaration variable or SGML Declaration file for parent document
  162. or DOCTYPE file or SGMLDECL from catalog. %d value of `sgml-doctype'.
  163.  
  164. ** `sgml-set-face'
  165.  
  166. Now automatically sets faces for all visible text, with a delay of 1s.
  167.  
  168. ** `sgml-exposed-tags'
  169.  
  170. The list of tag names that remain visible, despite `M-x
  171. sgml-hide-tags'. Each name is a lowercase string, and start-tags and
  172. end-tags must be listed individually.
  173.  
  174. ** `sgml-auto-activate-dtd'
  175.  
  176. PSGML was behaving inconsistent when a new file was loaded. If the
  177. variable `sgml-set-face' was true the DTD would automatically be
  178. activated (loaded or parsed), but only if psgml-parse already loaded.
  179.  
  180. Rather than let `sgml-set-face' decide if the DTD is activated, there
  181. is now a distinct option for this. This option works even the first
  182. time.
  183.  
  184. If non-nil, loading a sgml-file will automatically try to activate its
  185. DTD. Activation means either to parse the document type declaration or
  186. to load a previously saved parsed DTD. The name of the activated DTD
  187. will be shown in the mode line.
  188.  
  189. * Various
  190.  
  191. ** Tracing catalog lookup
  192.  
  193. To help debug entity lookup there is a new option
  194. `sgml-trace-entity-lookup'. If this option is t messages will be logged
  195. in *SGML LOG* buffer when external entities are looked up. These
  196. messages shows entity, catalogs searched, and entry type in catalog
  197. where entity was found.
  198.  
  199. ** Translating between characters and entity references
  200.  
  201. Set the variable `sgml-display-char-list-filename' to a file that
  202. contains mappings between all characters present in the presentation
  203. character set, and their "standard replacement text" names, e.g. "σ" ->
  204. "[aring ]", e.t.c. The default value for this variable is
  205. `iso88591.map'.
  206.  
  207. Use the functions (also in the Modify menu)
  208. `sgml-charent-to-display-char' and `sgml-display-char-to-charent' to
  209. translate between entities and characters.
  210.  
  211. ** Handling of missing DOCTYPE
  212.  
  213. If the document prolog does not contain a document type declaration,
  214. PSGML will try to supply one on the form `<!DOCTYPE DocTypeName
  215. SYSTEM>' If the variable `sgml-default-doctype-name' is defined this
  216. will be used for the document type name, otherwise the GI of the first
  217. start tag will be used. I.e., if the document starts with `<book>', a
  218. document type declaration `<!DOCTYPE book SYSTEM>' will be assumed.
  219.  
  220. ** Handling of tags for undefined elements
  221.  
  222. *** Start-tags for undefined elements will either be ignored, if
  223. `sgml-ignore-undefined-elements' is `t', or assumed to be acceptable in
  224. the current element and defined with `O O ANY'.
  225.  
  226. *** An end-tag for an element that is not currently open will be
  227. ignored.
  228.  
  229. ** Cleaned up Markup menu
  230.  
  231. The removed entries can be added with sgml-custom-markup:
  232.  
  233. (setq sgml-custom-markup
  234.       '(("<!entity ... >" "<!entity \r>\n")
  235.         ("<!attlist ... >" "<!attlist \r>\n")
  236.         ("<!element ... >" "<!element \r>\n")
  237.         ("<!doctype ...>" "<!doctype \r -- public or system --\n[\n]>\n")
  238.         ("Local variables comment" "<!--\nLocal variables:\n\rEnd:\n-->\n")
  239.         ("Comment" "<!-- \r -->\n") ))
  240.  
  241. ** New commands
  242.  
  243. Thanks to David Megginson the custom menus are now reachable from the
  244. keyboard:
  245.  
  246. `C-c C-u C-d' (`sgml-custom-dtd')
  247.  
  248. `C-c C-u C-m' (`sgml-custom-markup')
  249.  
  250. * Changes to API
  251.  
  252. ** New hooks
  253.  
  254. *** `sgml-close-element-hook'
  255.  
  256. The hook run by `sgml-close-element'. These functions are invoked with
  257. `sgml-current-tree' bound to the element just parsed.
  258.  
  259. *** `sgml-new-attribute-list-function'
  260.  
  261. This hook is run when a new element is inserted to construct the
  262. attribute specification list. The default function prompts for the
  263. required attributes.
  264.  
  265. *** `sgml-doctype-parsed-hook'
  266.  
  267. This hook is called after the doctype has been parsed. It can be used
  268. to load any additional information into the DTD structure.
  269.  
  270. Example: add description to element types
  271.  
  272. (defun set-help-info ()
  273.   (let ((help '(("para" "A Paragraph")
  274.         ("q"    "A Quotation")
  275.         ("date" "A Date")))
  276.     (dtd (sgml-pstate-dtd sgml-buffer-parse-state)))
  277.     (loop for h in help do
  278.       (setf (sgml-eltype-appdata (sgml-lookup-eltype (first h) dtd)
  279.                      'help-string)
  280.         (second h)))))
  281. (add-hook 'sgml-doctype-parsed-hook 'set-help-info)
  282. (defun sgml-help-for-element ()
  283.   (interactive)
  284.   (let* ((el (sgml-find-element-of (point)))
  285.      (help (sgml-element-appdata el 'help-string)))
  286.     (and help
  287.      (message "%s" help))))
  288.  
  289. *** sgml-sysid-resolve-functions
  290.  
  291. This variable should contain a list of functions. Each function should
  292. take one argument, the system identifier of an entity. If the function
  293. can handle that identifier, it should insert the text of the entity
  294. into the current buffer at point and return t. If the system identifier
  295. is not handled the function should return nil.
  296.  
  297. Example use: Support URLs as system identifiers
  298.  
  299. (defun sgml-url-sysid (sysid)
  300.   (cond ((string-match "^\\([a-z]+\\):" sysid) ; looks like url
  301.      (require 'url)
  302.      (set-buffer (prog1 (current-buffer)
  303.                (url-retrieve sysid)))
  304.      (insert-buffer url-working-buffer)
  305.      t)))
  306. (add-hook 'sgml-sysid-resolve-functions 'sgml-url-sysid)
  307.  
  308. ** New file psgml-api.el
  309.  
  310. This file contain API-functions that are not used by other parts of
  311. psgml. Use `(require 'psgml-api)' to use the API functions (psgml-api
  312. includes the rest of the psgml files).
  313.  
  314. Local variables:
  315. mode: text
  316. mode: outline
  317. end:
  318.